home *** CD-ROM | disk | FTP | other *** search
PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) NNNNAAAAMMMMEEEE _pppp_aaaa_rrrr - process activity reporter / truss-like system call tracer SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_cccc_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_c_m_d _a_r_g_s ...] _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_cccc_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_----_pppp _p_i_d] [_----_pppp ...] _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_cccc_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] [_----_tttt _t_i_m_e] _pppp_aaaa_rrrr [_rrrr_eeee_pppp_oooo_rrrr_tttt_----_oooo_pppp_tttt_iiii_oooo_nnnn_ssss] DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _pppp_aaaa_rrrr is a system utility program that reports on system call and scheduling activity for one or more processes. _pppp_aaaa_rrrr can be used to trace the activity of a single process, a related group of processes, or the system as a whole. See the _EEEE_XXXX_AAAA_MMMM_PPPP_LLLL_EEEE_SSSS section near the end for some examples on how par is commonly used. When tracing system calls, _pppp_aaaa_rrrr(1) prints a report showing all system calls made by the subject processes complete with arguments and return values. In this mode, _pppp_aaaa_rrrr(1) also reports all signals delivered to the subject processes. When tracing scheduler actions, _pppp_aaaa_rrrr(1) reports all scheduling events taking place in the system during the measurement period. The report shows each time a process is put on a run queue, started on a processor, and descheduled from a processor. All scheduling events are timestamped and, when available, include the reason for the action. _pppp_aaaa_rrrr(1) works by processing the output of _pppp_aaaa_dddd_cccc(1). This can be done in two ways: _pppp_aaaa_dddd_cccc can be run separately and the output saved in a file (to be fed to _pppp_aaaa_rrrr as a separate operation), or _pppp_aaaa_dddd_cccc can be invoked by _pppp_aaaa_rrrr to perform the data collection and reporting in one step. _pppp_aaaa_rrrr can generate different reports from data collected by _pppp_aaaa_dddd_cccc depending on the reporting options that are specified. The ability to generate different reports from a single set of data is one reason that it is often desirable to run the data collection as a separate step. There are three things that need to be specified on the _pppp_aaaa_rrrr command line: what information to report, what data should be collected, and what objects are to be monitored. _pppp_aaaa_rrrr can be run without displaying any information (collection-only) or without collecting any event data (report-only). Objects to be monitored may be running processes or commands that are started up specifically for the purpose of collecting event data. If an object is specified for monitoring (either a command to launch or an existing process), but no data collection or reporting options are specified, then _pppp_aaaa_rrrr defaults to collecting and reporting system call and signal data. PPPPaaaaggggeeee 1111 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) _DDDD_aaaa_tttt_aaaa _CCCC_oooo_llll_llll_eeee_cccc_tttt_iiii_oooo_nnnn _OOOO_pppp_tttt_iiii_oooo_nnnn_ssss These options should only be supplied when event data is to be collected by running a command or by tracing an already running process or set of processes. _----_ssss Collect system call and signal data for the ccccmmmmdddd or those processes specified via the ----pppp option. If neither are specified, system call and signal data for all processes that you have permissions to access will be collected. _----_rrrr Collect scheduler activity data for the ccccmmmmdddd or those processes specified via the ----pppp option. If neither are specified, scheduler activity data for the entire system will be collected. _----_kkkk Collect disk i/o activity data. _----_iiii Inherit tracing to forked children of object processes. _----_OOOO _f_i_l_e Write raw event data to the specified _f_i_l_e. _----_CCCC Collect CXFS actitity events. _RRRR_eeee_pppp_oooo_rrrr_tttt_iiii_nnnn_gggg _OOOO_pppp_tttt_iiii_oooo_nnnn_ssss Note that various options are meaningful only when the event data includes relevant information. For example, requesting a report on system call activity is useless if no system call events are collected (with the _----_ssss option) or none are present in a file of previously collected data. _----_SSSS Print a summary of system calls and signal counts. _----_SSSS_SSSS Print both the summary of system call activity and a trace of each system call and signal action. _----_QQQQ Print a summary of scheduling work. _----_QQQQ_QQQQ Print both the summary of scheduling work and a trace of each scheduler operation. _----_QQQQ_QQQQ_QQQQ In addition to the detailed scheduling trace, print the contents of the global run queue after each scheduler operation. _----_nnnn _s_y_s_c_a_l_l Show records for the specified system call, where the system call is specified by name or number. This option may be specified multiple times. Specifying this option automatically enables detailed system call reporting. PPPPaaaaggggeeee 2222 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) _----_eeee _s_y_s_c_a_l_l Exclude the specified system call from the report. This option may be specified multiple times. Specifying this option automatically enables detailed system call reporting. Other options that control the format and content of reports are: _----_AAAA Show system call parameter data (e.g. from a _rrrr_eeee_aaaa_dddd call) in character format. Non printable characters are output in hex. Normally, _pppp_aaaa_rrrr selects ASCII or binary format for data according to the data content. _----_aaaa _l_e_n Set the maximum number of bytes printed in character format for data (e.g. from a _rrrr_eeee_aaaa_dddd call) to _l_e_n. This value defaults to 30 bytes. The larger of the value for this option and the _----_bbbb option is used to inform _pppp_aaaa_dddd_cccc, if appropriate, how much data to collect (see the _----_IIII option of _pppp_aaaa_dddd_cccc). The maximum value for this option is 4096 bytes. _----_BBBB Show system call parameter data (e.g. from a _rrrr_eeee_aaaa_dddd call) in hex binary format. Normally, _pppp_aaaa_rrrr selects ASCII or binary format for data according to the data content. _----_bbbb _l_e_n Set the maximum number of bytes printed in binary format for data (e.g. from a _rrrr_eeee_aaaa_dddd call) to _l_e_n. This value defaults to 16. The maximum value for this option is 4096 bytes. _----_cccc Do not print CPU numbers in detailed trace reports. _----_dddd Show each system call as two entries: one for when the system call is begun and a second when the system call completes. Normally _pppp_aaaa_rrrr displays system calls as a single line, showing input arguments, output arguments and return values. The time displayed is the time of the start of the system call. This compaction is done unless the duration of the system call exceeds a nominal threshold (25 microseconds by default). With the _----_dddd option system calls are always displayed as beginning and ending operations. _----_llll Show system call output in a long format that includes each process name and the CPU on which it is run. By default _pppp_aaaa_rrrr will use this format whenever it is needed to avoid confusion; e.g. when multiple processes might appear in the report. Otherwise, _pppp_aaaa_rrrr uses a more compact format that does not show the process name or CPU number. This option is only useful when a detailed report is requested; e.g. _----_QQQQ_QQQQ and/or _----_SSSS_SSSS. _----_oooo _f_i_l_e Print all output (including errors) to _ffff_iiii_llll_eeee. This is useful when monitoring a program that itself does output. PPPPaaaaggggeeee 3333 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) _----_PPPP _p_i_d List activity only for the process specified by _p_i_d. Note that this is markedly different from the _----_pppp _p_i_d option that requests that the named _p_i_d be traced. Thus one could request that processes 100 and 101 be traced, but only report system calls for process 101. This option is typically specified when _pppp_aaaa_dddd_cccc has been used to collect data on a number of processes - often either by collecting for all processes on the system or all processes descended from a specified process. _----_TTTT Print thread and process IDs. This is especially useful for pthread applications which may have more then one thread of execution operating under the same process ID. _----_uuuu Print event times as milliseconds and microseconds since the last displayed event. _OOOO_bbbb_jjjj_eeee_cccc_tttt _SSSS_pppp_eeee_cccc_iiii_ffff_iiii_cccc_aaaa_tttt_iiii_oooo_nnnn _----_pppp _p_i_d Trace the process specified by _p_i_d. If the _----_iiii flag is specified then any child processes created by _p_i_d will also be traced. Multiple _----_pppp options may be given to trace multiple processes. In this mode, _pppp_aaaa_dddd_cccc(1) is automatically invoked by _pppp_aaaa_rrrr. _----_tttt _t_i_m_e Terminate the trace after _t_i_m_e seconds. Primarily useful when tracing the system as a whole. _[[[[_c_o_m_m_a_n_d _a_r_g_u_m_e_n_t_s ..._]]]] Run the specified command with tracing enabled. If the _----_iiii option is specified, any child processes that are created by _c_o_m_m_a_n_d will also be traced. In this mode, _pppp_aaaa_dddd_cccc(1) is automatically invoked by _pppp_aaaa_rrrr. _n_o_t_h_i_n_g If no specification of an object is given, all specified activity will be traced for the system as a whole. Note that only the superuser can trace the system as a whole. In this mode, _pppp_aaaa_dddd_cccc(1) is automatically invoked by _pppp_aaaa_rrrr. If no data collection options are specified and no object is specified, _pppp_aaaa_rrrr will read standard input as output from _pppp_aaaa_dddd_cccc and report the data according to the reporting options selected. IIIINNNNTTTTEEEERRRRPPPPRRRREEEETTTTIIIINNNNGGGG TTTTHHHHEEEE RRRREEEEPPPPOOOORRRRTTTTSSSS _pppp_aaaa_rrrr generates several different reports. Summary reports, requested with the _----_SSSS and _----_QQQQ options, are straightforward and are not described here. Other reports provide a detailed listing of the event data; they are composed of lines of the form: <_t_i_m_e>mS[<_c_p_u>] <_n_a_m_e>(<_p_i_d>): ... with the following explanations: PPPPaaaaggggeeee 4444 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) <_t_i_m_e> The time of the event in milliseconds relative to the start of data collection. If the _----_uuuu option is supplied, <_t_i_m_e> will be followed by the number of microseconds since the last event (enclosed in parenthesis). <_c_p_u> The CPU number the event was generated on. This is displayed if a long listing is requested with the _----_llll option or if there is more than one CPU in the system that data is collected on. The _----_cccc option can be used to disable display of the CPU number. <_n_a_m_e> The name of the process (as displayed by _pppp_ssss(1)). This is only displayed for a long listing. <_p_i_d> The PID of the process. This is only displayed for a long listing. The remaining information that _pppp_aaaa_rrrr prints depends on the type of event that is being reported. For system calls each line is of the form: ... : <_s_y_s_c_a_l_l>(<_a_r_g_1>, <_a_r_g_2>, ..., <_a_r_g_N>) = <_r_e_s_u_l_t> with the following information: <_s_y_s_c_a_l_l> The system call name. If the system call being displayed is split into 2 events, the event marking the end of the system call will have _EEEE_NNNN_DDDD_---- prepended to the name. See below for some help in decoding system call names. _pppp_aaaa_rrrr attempts to print an entire system call - input arguments, output arguments, and error return on a single line. It does not do this if the _----_dddd option is given or if another event needs to be reported between the start and end of a call. <_a_r_g_N> The system call arguments. Various amounts of decoding of arguments is done. Some system calls have complex arguments that have both input and output values. If an entire system call is printed on one single line, these input/output arguments have the words _IIII_NNNN_:::: or _OOOO_UUUU_TTTT_:::: printed before the decoding of the argument. Some complex indirect parameters are displayed symbolically using their C structure definition. Note that not all indirect parameter values are available; some are not returned by the operation system while others may not be copied out because doing so would exceed the maximum amount of indirect data to included in an event (see the _----_IIII option for _pppp_aaaa_dddd_cccc). <_r_e_s_u_l_t> The error status or return value of the system call. For system calls that simply return success or failure, _pppp_aaaa_rrrr prints _OOOO_KKKK for success, and the error value for failure. System calls that return values have those values printed. PPPPaaaaggggeeee 5555 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) Since _pppp_aaaa_rrrr's information comes straight from the operating system at the system call level, some calls that _pppp_aaaa_rrrr presents may not seem to correspond to the calls that the application made. This is because some system calls are implemented in runtime libraries on top of more primitive system calls. Some notable examples of this are: _wwww_aaaa_iiii_tttt_ssss_yyyy_ssss is the underlying system call for all wait-like calls. Its arguments are the same as _wwww_aaaa_iiii_tttt_iiii_dddd(2) except that it takes as a fifth argument a pointer to a _s_t_r_u_c_t _r_u_s_a_g_e. _????_xxxx_ssss_tttt_aaaa_tttt These stat calls are the same as the application entry points except that the first argument is a version number. _ssss_iiii_gggg_aaaa_cccc_tttt_iiii_oooo_nnnn is used to implement all type signal routines. It takes one additional parameter than the application entry point - the address of the library handler that all signals funnel through. _ssss_iiii_gggg_rrrr_eeee_tttt_uuuu_rrrr_nnnn is used to return a process from its signal handler to the previous context. _ssss_iiii_gggg_pppp_oooo_llll_llll is used to implement _ssss_iiii_gggg_wwww_aaaa_iiii_tttt_rrrr_tttt(3) and _ssss_iiii_gggg_tttt_iiii_mmmm_eeee_dddd_wwww_aaaa_iiii_tttt(3). _EEEE_RRRR_EEEE_SSSS_TTTT_AAAA_RRRR_TTTT is returned when a system call should be automatically restarted after being interrupted by a signal (see _ssss_iiii_gggg_aaaa_cccc_tttt_iiii_oooo_nnnn). This error is never actually returned to the user but _pppp_aaaa_rrrr reports the re-invocation of a system call as an error. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS _pppp_aaaa_rrrr _llll_ssss _//// Display a system call trace and summary for the command 'ls /'. (_pppp_aaaa_rrrr supplies the implicit -sSS options because a command to launch was specified without any reporting or collection options.): apache% par ls / MISER de hosts mnt par.out tmp var RTMON debug hw ns proc tmp_mnt TESTS dev lib opt proj unix bin doouf lib32 out.1 rtmon.out unix.benf build etc lib64 output.1 sbin unix.orig build11 ficus miser par stand usr 0mS[ 1] was sent signal SIGUSR1 0mS[ 3] received signal SIGUSR1 (handler 0x10002560) 0mS[ 3] END-pause() errno = 4 (Interrupted function call) 1mS[ 3] sigreturn(0x7fff2b40) OK 1mS[ 3] execve(./ls, 0x7fff2f6c, 0x7fff2f78) 262mS[ 3] END-execve() errno = 2 (No such file or directory) 262mS[ 3] execve(/usr/sbin/ls, 0x7fff2f6c, 0x7fff2f78) errno = 2 (No such file or directory) 263mS[ 3] execve(/usr/bsd/ls, 0x7fff2f6c, 0x7fff2f78) errno = 2 (No such file or directory) 264mS[ 3] execve(/sbin/ls, 0x7fff2f6c, 0x7fff2f78) 274mS[ 3] END-execve() OK 274mS[ 3] open(/lib32/rld, O_RDONLY, 04) = 3 PPPPaaaaggggeeee 6666 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) 275mS[ 3] read(3, <7f 45 4c 46 01 02 01 00 00 00 00 00 00 00 00 00>..., 512) = 512 276mS[ 3] elfmap(3, 0x7fff2d54, 2) = 0xfb60000 276mS[ 3] close(3) OK 279mS[ 3] getpagesize() = 16384 279mS[ 3] sysinfo(_MIPS_SI_PROCESSORS, 0x7fff2dc0, 257) = 43 281mS[ 3] open(/dev/zero, O_RDONLY, 0) = 3 282mS[ 3] mmap(0xfbd4000, 16384, PROT_WRITE|PROT_READ, MAP_PRIVATE, 3, 0) = 0xfbd4000 282mS[ 3] close(3) OK ... Note that output from the command is intermixed with the system call report; the _----_oooo option can be used to direct the report to a file separately from any output generated by the command. The report about the command receiving a SIGUSR1 signal is expected; this is done as part of the normal procedure for starting up a program with tracing. Finally, note that many system call parameters are displayed symbolically and that the _i_n_d_i_r_e_c_t _v_a_l_u_e of many parameters is displayed; e.g. ``/lib32/rld'' and ``/dev/zero'' for open. _pppp_aaaa_rrrr _----_rrrr_ssss_SSSS_SSSS_QQQQ_QQQQ _----_OOOO _llll_ssss_...._pppp_aaaa_dddd_cccc _llll_ssss _//// Report on system calls and scheduling activities for the command 'ls /', and also record the raw event data in the file _l_s._p_a_d_c. _pppp_aaaa_rrrr _----_oooo _oooo_uuuu_tttt_ffff_iiii_llll_eeee _----_nnnn _oooo_pppp_eeee_nnnn _----_nnnn _cccc_llll_oooo_ssss_eeee _llll_ssss Trace only the open and close system calls. Write the resulting output to _o_u_t_f_i_l_e. Note that it is not necessary to specify _----_SSSS_SSSS options since they are implied by the _----_nnnn option. Also, the _----_ssss option is not required because system calls are the default data to collect when a command is specified. _pppp_aaaa_rrrr _----_oooo _oooo_uuuu_tttt_ffff_iiii_llll_eeee _----_iiii _----_tttt _3333_0000 _----_pppp _1111 Trace all processes started directly by process 1 (which is the iiiinnnniiiitttt process, the ancestor of all user processes) for thirty seconds, and store the report in the file _o_u_t_f_i_l_e. Note that the _----_iiii option will cause only processes newly created by iiiinnnniiiitttt to be traced; i.e. it does not mark all existing child processes for tracing. LLLLIIIIMMMMIIIITTTTAAAATTTTIIIIOOOONNNNSSSS To reduce system load, when collecting system call event data, system calls executed by _pppp_aaaa_dddd_cccc(1) and _rrrr_tttt_mmmm_oooo_nnnn_dddd_((((_1111_)))) are not recorded. This can lead to some inexplicable gaps when tracing complete system activity. The process name associated with an event may be misleading. This is because a process's name may change between the time an event is generated and the time the event collection process (_rrrr_tttt_mmmm_oooo_nnnn_dddd) checks for the name. For example, a process may generate events then exit before _rrrr_tttt_mmmm_oooo_nnnn_dddd is able to query the system for the process name. In this case the events will show up as being associated with a process without a name. PPPPaaaaggggeeee 7777 PPPPAAAARRRR((((1111)))) PPPPAAAARRRR((((1111)))) A user must have the CAP_PROC_MGT capability to monitor setuid processes or processes with capabilities, and the CAP_DAC_READ_SEARCH capability to monitor a process owned by another user. Under Trusted IRIX, the CAP_MAC_READ capability is also required to monitor processes that are not dominated by the user's MAC label. See _cccc_aaaa_pppp_aaaa_bbbb_iiii_llll_iiii_tttt_iiii_eeee_ssss(4) and _dddd_oooo_mmmm_iiii_nnnn_aaaa_nnnn_cccc_eeee(5) for more information. SSSSEEEEEEEE AAAALLLLSSSSOOOO _pppp_aaaa_dddd_cccc(1), _rrrr_tttt_mmmm_oooo_nnnn_dddd(1), _cccc_aaaa_pppp_aaaa_bbbb_iiii_llll_iiii_tttt_iiii_eeee_ssss(4), _dddd_oooo_mmmm_iiii_nnnn_aaaa_nnnn_cccc_eeee(5). PPPPaaaaggggeeee 8888 
